/*
 * Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.management.remote;

import com.sun.jmx.mbeanserver.Util;
import java.io.IOException;
import java.net.MalformedURLException;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.Iterator;
import java.util.ServiceLoader;
import java.util.StringTokenizer;
import java.security.AccessController;
import java.security.PrivilegedAction;

import com.sun.jmx.remote.util.ClassLogger;
import com.sun.jmx.remote.util.EnvHelp;
import sun.reflect.misc.ReflectUtil;


/**
 * <p>Factory to create JMX API connector clients.  There
 * are no instances of this class.</p>
 *
 * <p>Connections are usually made using the {@link
 * #connect(JMXServiceURL) connect} method of this class.  More
 * advanced applications can separate the creation of the connector
 * client, using {@link #newJMXConnector(JMXServiceURL, Map)
 * newJMXConnector} and the establishment of the connection itself, using
 * {@link JMXConnector#connect(Map)}.</p>
 *
 * <p>Each client is created by an instance of {@link
 * JMXConnectorProvider}.  This instance is found as follows.  Suppose
 * the given {@link JMXServiceURL} looks like
 * <code>"service:jmx:<em>protocol</em>:<em>remainder</em>"</code>.
 * Then the factory will attempt to find the appropriate {@link
 * JMXConnectorProvider} for <code><em>protocol</em></code>.  Each
 * occurrence of the character <code>+</code> or <code>-</code> in
 * <code><em>protocol</em></code> is replaced by <code>.</code> or
 * <code>_</code>, respectively.</p>
 *
 * <p>A <em>provider package list</em> is searched for as follows:</p>
 *
 * <ol>
 *
 * <li>If the <code>environment</code> parameter to {@link
 * #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the
 * key <code>jmx.remote.protocol.provider.pkgs</code> then the
 * associated value is the provider package list.
 *
 * <li>Otherwise, if the system property
 * <code>jmx.remote.protocol.provider.pkgs</code> exists, then its value
 * is the provider package list.
 *
 * <li>Otherwise, there is no provider package list.
 *
 * </ol>
 *
 * <p>The provider package list is a string that is interpreted as a
 * list of non-empty Java package names separated by vertical bars
 * (<code>|</code>).  If the string is empty, then so is the provider
 * package list.  If the provider package list is not a String, or if
 * it contains an element that is an empty string, a {@link
 * JMXProviderException} is thrown.</p>
 *
 * <p>If the provider package list exists and is not empty, then for
 * each element <code><em>pkg</em></code> of the list, the factory
 * will attempt to load the class
 *
 * <blockquote>
 * <code><em>pkg</em>.<em>protocol</em>.ClientProvider</code>
 * </blockquote>
 *
 * <p>If the <code>environment</code> parameter to {@link
 * #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the
 * key <code>jmx.remote.protocol.provider.class.loader</code> then the
 * associated value is the class loader to use to load the provider.
 * If the associated value is not an instance of {@link
 * java.lang.ClassLoader}, an {@link
 * java.lang.IllegalArgumentException} is thrown.</p>
 *
 * <p>If the <code>jmx.remote.protocol.provider.class.loader</code>
 * key is not present in the <code>environment</code> parameter, the
 * calling thread's context class loader is used.</p>
 *
 * <p>If the attempt to load this class produces a {@link
 * ClassNotFoundException}, the search for a handler continues with
 * the next element of the list.</p>
 *
 * <p>Otherwise, a problem with the provider found is signalled by a
 * {@link JMXProviderException} whose {@link
 * JMXProviderException#getCause() <em>cause</em>} indicates the underlying
 * exception, as follows:</p>
 *
 * <ul>
 *
 * <li>if the attempt to load the class produces an exception other
 * than <code>ClassNotFoundException</code>, that is the
 * <em>cause</em>;
 *
 * <li>if {@link Class#newInstance()} for the class produces an
 * exception, that is the <em>cause</em>.
 *
 * </ul>
 *
 * <p>If no provider is found by the above steps, including the
 * default case where there is no provider package list, then the
 * implementation will use its own provider for
 * <code><em>protocol</em></code>, or it will throw a
 * <code>MalformedURLException</code> if there is none.  An
 * implementation may choose to find providers by other means.  For
 * example, it may support the <a
 * href="{@docRoot}/../technotes/guides/jar/jar.html#Service Provider">
 * JAR conventions for service providers</a>, where the service
 * interface is <code>JMXConnectorProvider</code>.</p>
 *
 * <p>Every implementation must support the RMI connector protocol with
 * the default RMI transport, specified with string <code>rmi</code>.
 * An implementation may optionally support the RMI connector protocol
 * with the RMI/IIOP transport, specified with the string
 * <code>iiop</code>.</p>
 *
 * <p>Once a provider is found, the result of the
 * <code>newJMXConnector</code> method is the result of calling {@link
 * JMXConnectorProvider#newJMXConnector(JMXServiceURL, Map) newJMXConnector}
 * on the provider.</p>
 *
 * <p>The <code>Map</code> parameter passed to the
 * <code>JMXConnectorProvider</code> is a new read-only
 * <code>Map</code> that contains all the entries that were in the
 * <code>environment</code> parameter to {@link
 * #newJMXConnector(JMXServiceURL, Map)
 * JMXConnectorFactory.newJMXConnector}, if there was one.
 * Additionally, if the
 * <code>jmx.remote.protocol.provider.class.loader</code> key is not
 * present in the <code>environment</code> parameter, it is added to
 * the new read-only <code>Map</code>.  The associated value is the
 * calling thread's context class loader.</p>
 *
 * @since 1.5
 */
public class JMXConnectorFactory {

  /**
   * <p>Name of the attribute that specifies the default class
   * loader. This class loader is used to deserialize return values and
   * exceptions from remote <code>MBeanServerConnection</code>
   * calls.  The value associated with this attribute is an instance
   * of {@link ClassLoader}.</p>
   */
  public static final String DEFAULT_CLASS_LOADER =
      "jmx.remote.default.class.loader";

  /**
   * <p>Name of the attribute that specifies the provider packages
   * that are consulted when looking for the handler for a protocol.
   * The value associated with this attribute is a string with
   * package names separated by vertical bars (<code>|</code>).</p>
   */
  public static final String PROTOCOL_PROVIDER_PACKAGES =
      "jmx.remote.protocol.provider.pkgs";

  /**
   * <p>Name of the attribute that specifies the class
   * loader for loading protocol providers.
   * The value associated with this attribute is an instance
   * of {@link ClassLoader}.</p>
   */
  public static final String PROTOCOL_PROVIDER_CLASS_LOADER =
      "jmx.remote.protocol.provider.class.loader";

  private static final String PROTOCOL_PROVIDER_DEFAULT_PACKAGE =
      "com.sun.jmx.remote.protocol";

  private static final ClassLogger logger =
      new ClassLogger("javax.management.remote.misc", "JMXConnectorFactory");

  /**
   * There are no instances of this class.
   */
  private JMXConnectorFactory() {
  }

  /**
   * <p>Creates a connection to the connector server at the given
   * address.</p>
   *
   * <p>This method is equivalent to {@link
   * #connect(JMXServiceURL, Map) connect(serviceURL, null)}.</p>
   *
   * @param serviceURL the address of the connector server to connect to.
   * @return a <code>JMXConnector</code> whose {@link JMXConnector#connect connect} method has been
   * called.
   * @throws NullPointerException if <code>serviceURL</code> is null.
   * @throws IOException if the connector client or the connection cannot be made because of a
   * communication problem.
   * @throws SecurityException if the connection cannot be made for security reasons.
   */
  public static JMXConnector connect(JMXServiceURL serviceURL)
      throws IOException {
    return connect(serviceURL, null);
  }

  /**
   * <p>Creates a connection to the connector server at the given
   * address.</p>
   *
   * <p>This method is equivalent to:</p>
   *
   * <pre>
   * JMXConnector conn = JMXConnectorFactory.newJMXConnector(serviceURL,
   *                                                         environment);
   * conn.connect(environment);
   * </pre>
   *
   * @param serviceURL the address of the connector server to connect to.
   * @param environment a set of attributes to determine how the connection is made.  This parameter
   * can be null.  Keys in this map must be Strings.  The appropriate type of each associated value
   * depends on the attribute.  The contents of <code>environment</code> are not changed by this
   * call.
   * @return a <code>JMXConnector</code> representing the newly-made connection.  Each successful
   * call to this method produces a different object.
   * @throws NullPointerException if <code>serviceURL</code> is null.
   * @throws IOException if the connector client or the connection cannot be made because of a
   * communication problem.
   * @throws SecurityException if the connection cannot be made for security reasons.
   */
  public static JMXConnector connect(JMXServiceURL serviceURL,
      Map<String, ?> environment)
      throws IOException {
    if (serviceURL == null) {
      throw new NullPointerException("Null JMXServiceURL");
    }
    JMXConnector conn = newJMXConnector(serviceURL, environment);
    conn.connect(environment);
    return conn;
  }

  private static <K, V> Map<K, V> newHashMap() {
    return new HashMap<K, V>();
  }

  private static <K> Map<K, Object> newHashMap(Map<K, ?> map) {
    return new HashMap<K, Object>(map);
  }

  /**
   * <p>Creates a connector client for the connector server at the
   * given address.  The resultant client is not connected until its
   * {@link JMXConnector#connect(Map) connect} method is called.</p>
   *
   * @param serviceURL the address of the connector server to connect to.
   * @param environment a set of attributes to determine how the connection is made.  This parameter
   * can be null.  Keys in this map must be Strings.  The appropriate type of each associated value
   * depends on the attribute.  The contents of <code>environment</code> are not changed by this
   * call.
   * @return a <code>JMXConnector</code> representing the new connector client.  Each successful
   * call to this method produces a different object.
   * @throws NullPointerException if <code>serviceURL</code> is null.
   * @throws IOException if the connector client cannot be made because of a communication problem.
   * @throws MalformedURLException if there is no provider for the protocol in
   * <code>serviceURL</code>.
   * @throws JMXProviderException if there is a provider for the protocol in <code>serviceURL</code>
   * but it cannot be used for some reason.
   */
  public static JMXConnector newJMXConnector(JMXServiceURL serviceURL,
      Map<String, ?> environment)
      throws IOException {

    final Map<String, Object> envcopy;
    if (environment == null) {
      envcopy = newHashMap();
    } else {
      EnvHelp.checkAttributes(environment);
      envcopy = newHashMap(environment);
    }

    final ClassLoader loader = resolveClassLoader(envcopy);
    final Class<JMXConnectorProvider> targetInterface =
        JMXConnectorProvider.class;
    final String protocol = serviceURL.getProtocol();
    final String providerClassName = "ClientProvider";
    final JMXServiceURL providerURL = serviceURL;

    JMXConnectorProvider provider = getProvider(providerURL, envcopy,
        providerClassName,
        targetInterface,
        loader);

    IOException exception = null;
    if (provider == null) {
      // Loader is null when context class loader is set to null
      // and no loader has been provided in map.
      // com.sun.jmx.remote.util.Service class extracted from j2se
      // provider search algorithm doesn't handle well null classloader.
      if (loader != null) {
        try {
          JMXConnector connection =
              getConnectorAsService(loader, providerURL, envcopy);
          if (connection != null) {
            return connection;
          }
        } catch (JMXProviderException e) {
          throw e;
        } catch (IOException e) {
          exception = e;
        }
      }
      provider = getProvider(protocol, PROTOCOL_PROVIDER_DEFAULT_PACKAGE,
          JMXConnectorFactory.class.getClassLoader(),
          providerClassName, targetInterface);
    }

    if (provider == null) {
      MalformedURLException e =
          new MalformedURLException("Unsupported protocol: " + protocol);
      if (exception == null) {
        throw e;
      } else {
        throw EnvHelp.initCause(e, exception);
      }
    }

    final Map<String, Object> fixedenv =
        Collections.unmodifiableMap(envcopy);

    return provider.newJMXConnector(serviceURL, fixedenv);
  }

  private static String resolvePkgs(Map<String, ?> env)
      throws JMXProviderException {

    Object pkgsObject = null;

    if (env != null) {
      pkgsObject = env.get(PROTOCOL_PROVIDER_PACKAGES);
    }

    if (pkgsObject == null) {
      pkgsObject =
          AccessController.doPrivileged(new PrivilegedAction<String>() {
            public String run() {
              return System.getProperty(PROTOCOL_PROVIDER_PACKAGES);
            }
          });
    }

    if (pkgsObject == null) {
      return null;
    }

    if (!(pkgsObject instanceof String)) {
      final String msg = "Value of " + PROTOCOL_PROVIDER_PACKAGES +
          " parameter is not a String: " +
          pkgsObject.getClass().getName();
      throw new JMXProviderException(msg);
    }

    final String pkgs = (String) pkgsObject;
    if (pkgs.trim().equals("")) {
      return null;
    }

    // pkgs may not contain an empty element
    if (pkgs.startsWith("|") || pkgs.endsWith("|") ||
        pkgs.indexOf("||") >= 0) {
      final String msg = "Value of " + PROTOCOL_PROVIDER_PACKAGES +
          " contains an empty element: " + pkgs;
      throw new JMXProviderException(msg);
    }

    return pkgs;
  }

  static <T> T getProvider(JMXServiceURL serviceURL,
      final Map<String, Object> environment,
      String providerClassName,
      Class<T> targetInterface,
      final ClassLoader loader)
      throws IOException {

    final String protocol = serviceURL.getProtocol();

    final String pkgs = resolvePkgs(environment);

    T instance = null;

    if (pkgs != null) {
      instance =
          getProvider(protocol, pkgs, loader, providerClassName,
              targetInterface);

      if (instance != null) {
        boolean needsWrap = (loader != instance.getClass().getClassLoader());
        environment.put(PROTOCOL_PROVIDER_CLASS_LOADER, needsWrap ? wrap(loader) : loader);
      }
    }

    return instance;
  }

  static <T> Iterator<T> getProviderIterator(final Class<T> providerClass,
      final ClassLoader loader) {
    ServiceLoader<T> serviceLoader =
        ServiceLoader.load(providerClass, loader);
    return serviceLoader.iterator();
  }

  private static ClassLoader wrap(final ClassLoader parent) {
    return parent != null ? AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
      @Override
      public ClassLoader run() {
        return new ClassLoader(parent) {
          @Override
          protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {
            ReflectUtil.checkPackageAccess(name);
            return super.loadClass(name, resolve);
          }
        };
      }
    }) : null;
  }

  private static JMXConnector getConnectorAsService(ClassLoader loader,
      JMXServiceURL url,
      Map<String, ?> map)
      throws IOException {

    Iterator<JMXConnectorProvider> providers =
        getProviderIterator(JMXConnectorProvider.class, loader);
    JMXConnector connection;
    IOException exception = null;
    while (providers.hasNext()) {
      JMXConnectorProvider provider = providers.next();
      try {
        connection = provider.newJMXConnector(url, map);
        return connection;
      } catch (JMXProviderException e) {
        throw e;
      } catch (Exception e) {
        if (logger.traceOn()) {
          logger.trace("getConnectorAsService",
              "URL[" + url +
                  "] Service provider exception: " + e);
        }
        if (!(e instanceof MalformedURLException)) {
          if (exception == null) {
            if (e instanceof IOException) {
              exception = (IOException) e;
            } else {
              exception = EnvHelp.initCause(
                  new IOException(e.getMessage()), e);
            }
          }
        }
        continue;
      }
    }
    if (exception == null) {
      return null;
    } else {
      throw exception;
    }
  }

  static <T> T getProvider(String protocol,
      String pkgs,
      ClassLoader loader,
      String providerClassName,
      Class<T> targetInterface)
      throws IOException {

    StringTokenizer tokenizer = new StringTokenizer(pkgs, "|");

    while (tokenizer.hasMoreTokens()) {
      String pkg = tokenizer.nextToken();
      String className = (pkg + "." + protocol2package(protocol) +
          "." + providerClassName);
      Class<?> providerClass;
      try {
        providerClass = Class.forName(className, true, loader);
      } catch (ClassNotFoundException e) {
        //Add trace.
        continue;
      }

      if (!targetInterface.isAssignableFrom(providerClass)) {
        final String msg =
            "Provider class does not implement " +
                targetInterface.getName() + ": " +
                providerClass.getName();
        throw new JMXProviderException(msg);
      }

      // We have just proved that this cast is correct
      Class<? extends T> providerClassT = Util.cast(providerClass);
      try {
        return providerClassT.newInstance();
      } catch (Exception e) {
        final String msg =
            "Exception when instantiating provider [" + className +
                "]";
        throw new JMXProviderException(msg, e);
      }
    }

    return null;
  }

  static ClassLoader resolveClassLoader(Map<String, ?> environment) {
    ClassLoader loader = null;

    if (environment != null) {
      try {
        loader = (ClassLoader)
            environment.get(PROTOCOL_PROVIDER_CLASS_LOADER);
      } catch (ClassCastException e) {
        final String msg =
            "The ClassLoader supplied in the environment map using " +
                "the " + PROTOCOL_PROVIDER_CLASS_LOADER +
                " attribute is not an instance of java.lang.ClassLoader";
        throw new IllegalArgumentException(msg);
      }
    }

    if (loader == null) {
      loader = Thread.currentThread().getContextClassLoader();
    }

    return loader;
  }

  private static String protocol2package(String protocol) {
    return protocol.replace('+', '.').replace('-', '_');
  }
}
